<!--
  ~ /**
  ~  IDEA Configurator
  ~  Copyright (C) 2006 Justin Tomich<tomichj at gmail dot com>
  ~
  ~  This program is free software; you can redistribute it and/or
  ~  modify it under the terms of the GNU General Public License as
  ~  published by the Free Software Foundation; either version 2 of the
  ~  License, or (at your option) any later version.
  ~
  ~  This program is distributed in the hope that it will be useful, but
  ~  WITHOUT ANY WARRANTY; without even the implied warranty of
  ~  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  ~  General Public License for more details.
  ~
  ~  You should have received a copy of the GNU General Public License
  ~  along with this program; if not, write to the Free Software
  ~  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  ~  */
  ~
  -->

<html>

<head>
    <meta http-equiv="Content-Language" content="en-us">
    <title>IdeaModule Ant Task</title>
</head>

<body>

<h2><a name="ant">IdeaModule</a></h2>

<h3>Description</h3>

<p>Generates a module configuration file for
    <a href="http://www.jetbrains.com/idea/">Intellij IDEA</a>.</p>

<p>Only generates "java" modules so far. Expect future changes (possibly
    including task name changes) to accomodate other IDEA module types.</p>

<p>IdeaModule strives to make module configuration simple for basic projects,
    but still provides the tools necessary for arbitrarily complex
    configuration.</p>

<p>IDEA manages the classpath through the notion of "libraries". IdeaModule
    allows you to configure IDEA's libraries in multiple ways. You can refer to
    global or project libraries, which are configured outside of the module. You
    can set the classpath as an attribute of &lt;ideamodule&gt;, you can set it
    through nested &lt;classpath&gt; elements, or you can set up nested &lt;moduleLibrary&gt;
    elements. You can even mix-and-match, although you're advised to use only
    the nested elements (&lt;classpath&gt; and &lt;moduleLibrary&gt;) if you
    want to control the ordering of your dependencies. IdeaModule will render
    classpath attribute/nested-element additions as Module Libraries.</p>

<p>Setting the classpath through nested &lt;moduleLibrary&gt; entries allows you
    to declare source, javadoc, and javadoc urls to associate with the module.
    You may also associate source, javadoc, and javadocurls indirectly by using
    IdeaModule's sourceproperty, javadocproperty, and javadocurlproperty
    attributes. When set, ideamodule will examine at every jar set via the
    classpath attribute or set using a nested &lt;classpath&gt; element. If a
    property defining that jar exists, IdeaModule will search for property with
    an identical name but prepended with the sourceproperty, javadocproperty, or
    javadocurlproperty, (plus a period) in it's name. If found, that property is
    treated as source or javadoc for the jar from the classpath. You can use
    this to easily add source and/or javadoc for libraries in a classpath by
    simply adding source, javadoc, and/or javadocurl properties to the
    project.</p>

<p>Example: sourceproperty is set to "source". A property named "foolib.jar" is
    defined and added to the classpath. A second property named
    "source.foolib.jar" is added to the project. The foolib module library will
    now be defined with both the classes jar and source jar, automatically, by
    dint of their associationg through the sourceproperty.

<p></p>

<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
</tr>
<tr>
    <td valign="top">rootDir</td>
    <td valign="top">Root directory of the module. Defaults to ant's
        baseDir.
    </td>
    <td valign="top" align="center">No</td>
</tr>
<tr>
    <td valign="top">excludeOutputPaths</td>
    <td valign="top">Exclude output paths from the build. Defaults to
        false.
    </td>
    <td valign="top" align="center">No</td>
</tr>
<tr>
    <td valign="top">moduleFile</td>
    <td valign="top">Name of the module file. Defaults to ant project's
        name.
    </td>
    <td valign="top" align="center">No</td>
</tr>
<tr>
    <td valign="top">relativePaths</td>
    <td valign="top">Use relative paths for files outside the root
        directory. Defaults to false (i.e. use absolute paths).
    </td>
    <td valign="top" align="center">No</td>
</tr>
<tr>
    <td valign="top">srcDir</td>
    <td valign="top">Set the source directory. Set either this property,
        srcPathRef, or one or more nested src elements.
    </td>
    <td valign="top" align="center">No</td>
</tr>
<tr>
    <td valign="top">srcPathRef</td>
    <td valign="top">Set the source directories to the given path. Set
        either this property, srcPathRef, or one or more nested src
        elements.
    </td>
    <td valign="top" align="center">No</td>
</tr>
<tr>
    <td valign="top">testsDir</td>
    <td valign="top">Set the test directories to the given path. Set either
        this property, srcPathRef, or one or more nested src elements.
    </td>
    <td valign="top" align="center">No</td>
</tr>
<tr>
    <td valign="top">testsPathRef</td>
    <td valign="top">Set the test directories to the given path reference.
        Set either this property, srcPathRef, or one or more nested src
        elements.
    </td>
    <td valign="top" align="center">No</td>
</tr>
<tr>
    <td valign="top">outputDir</td>
    <td valign="top">Set the folder that stores all project production
        compilation results.
    </td>
    <td valign="top" align="center">No</td>
</tr>
<tr>
    <td valign="top">testsOutputDir</td>
    <td valign="top">Set the folder that stores all project test compilation
        results
    </td>
    <td valign="top" align="center">No</td>
</tr>
<tr>
    <td valign="top">excludes</td>
    <td valign="top">Set folder(s) to be excluded roots, which will not be
        displayed in Project tab or otherwise included in IDEA. If listing
        more than one, they must be colon-delimited.
    </td>
    <td valign="top" align="center">No</td>
</tr>
<tr>
    <td valign="top">excludesPathRef</td>
    <td valign="top">Set the given path as excluded roots.</td>
    <td valign="top" align="center">No</td>
</tr>


<tr>
    <td valign="top">classpath</td>
    <td valign="top">Set the classpath as a colon-delimited list. You may
        EITHER set classpath OR use the &lt;dependencies&gt; subtask.
    </td>
    <td valign="top" align="center">No</td>
</tr>
<tr>
    <td valign="top">sourceProperty</td>
    <td valign="top">Set string that source properties must begin with to be
        automagically identified as source for a corresponging library.
    </td>
    <td valign="top" align="center">No</td>
</tr>
<tr>
    <td valign="top">javadocProperty</td>
    <td valign="top">Set string that javadoc properties must begin with to
        be automagically identified as source for a corresponging library.
    </td>
    <td valign="top" align="center">No</td>
</tr>
<tr>
    <td valign="top">javadocUrlProperty</td>
    <td valign="top">Set string that javadoc url properties must begin with
        to be automagically identified as source for a corresponging
        library.
    </td>
    <td valign="top" align="center">No</td>
</tr>
</table>

<h3>Parameters specified as nested elements</h3>

<!-- TODO -->

<h4><code>src</code>, <code>tests</code>, and <code>excludes</code></h4>

<p><code>&lt;ideamodule&gt;</code>'s <code>src</code>,
    <code>tests</code>, and <code>excludes</code> attributes are
    <a href="http://ant.apache.org/mahual/using.html#path">path-like
        structures</a>
    and can also be set via nested
    <code>&lt;src&gt;</code>,
    <code>&lt;tests&gt;</code> and
    <code>&lt;excludes&gt;</code> elements, respectively.</p>


<h4>classpathFilter</h4>

<p>Remove any jars from the classpath selected by this filter</p>

<table border="1" cellpadding="2" cellspacing="0">
    <tr>
        <td valign="top"><b>Attribute</b></td>
        <td valign="top"><b>Description</b></td>
        <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
        <td valign="top">pattern</td>
        <td valign="top">The pattern to be selected, conforming to java 1.5's
            regexp syntax.
        </td>
        <td valign="top" align="center">Yes</td>
    </tr>
</table>


<h4>Dependencies</h4>

<p>&lt;Dependencies&gt; is an optional element that allows you to specify what
    resources your module depends on, and the order in which the dependencies
    are resolved. The elements nested inside the dependencies tag are thus
    order-dependent. IDEA will process the libraries and modules in the order
    they appear below. This list corresponds to the "Dependencies" tab of IDEAs
    Project Structure window.</p>

<h4>Parameters specified as nested elements of &lt;dependencies&gt;</h4>

<h4>moduleSource</h4>

<p>Specifies the dependency order of the source from your module.</p>

<h4>jdk</h4>

<p>Specifies the dependency order of the jdk. If a jdk name is specified, that
    jdk will be used for the module, otherwise it will default to the project's
    jdk.</p>
<table border="1" cellpadding="2" cellspacing="0">
    <tr>
        <td valign="top"><b>Attribute</b></td>
        <td valign="top"><b>Description</b></td>
        <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
        <td valign="top">jdkName</td>
        <td valign="top">If set, uses the specified jdk rather than the
            project's default jdk.
        </td>
        <td valign="top" align="center">No</td>
    </tr>
</table>

<h4>classpath</h4>

<p>Specifies a classpath of jars to be added to the module's libraries. Each jar
    in the list will become a new Module Library entry (see IDEA's
    documentation, or &lt;moduleLibrary&gt; below). If you add libraries using
    the &lt;moduleLibrary&gt;, &lt;projectLibrary&gt;, or &lt;globalLibrary&gt;
    tags, you do not need to include those jars in a separate
    &lt;classpath&gt;.</p>

<p>If source, javadoc, or javadocurl properties are specified in the top-level
    element's attributes, and corresponding properties are found, then they will
    be added to the appropriate module library.</p>

<p>Classpath is a path-like structure.</p>

<h4>moduleLibrary</h4>

<p>Defines a module library.</p>

<table border="1" cellpadding="2" cellspacing="0">
    <tr>
        <td valign="top"><b>Attribute</b></td>
        <td valign="top"><b>Description</b></td>
        <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
        <td valign="top">exported</td>
        <td valign="top">If true, this library will be exported to other modules
            that depend upon this module.
        </td>
        <td valign="top" align="center">No</td>
    </tr>
    <tr>
        <td valign="top">classes</td>
        <td valign="top">jar/zip of classes for the library. Or use the nested
            &lt;classes&gt; element. This attribute, or a nested
        </td>
        <td valign="top" align="center">Yes, unless nested &lt;classes&gt;
            elements are present.
        </td>
    </tr>
    <tr>
        <td valign="top">sources</td>
        <td valign="top">Jar or directory of source files for the library. Or
            use the nested &lt;sources&gt; element.
        </td>
        <td valign="top" align="center">No</td>
    </tr>
    <tr>
        <td valign="top">javadoc</td>
        <td valign="top">Jar or directory of javadoc for the library. Or use the
            nested &lt;javadoc&gt; element.
        </td>
        <td valign="top" align="center">No</td>
    </tr>
    <tr>
        <td valign="top">javadocUrl</td>
        <td valign="top">Url to javadoc. No nested element is offered... :(</td>
        <td valign="top" align="center">No</td>
    </tr>
</table>

<p>moduleLibrary offers the following nested elements which are path-like
    structures: &lt;classes&gt;, &lt;sources&gt;, and &lt;javadoc&gt;.


<h4>projectLibrary</h4>

<p>Depend on a library defined at the project level. Project libraries are
    referred to by name. The project library must already exist.</p>
<table border="1" cellpadding="2" cellspacing="0">
    <tr>
        <td valign="top"><b>Attribute</b></td>
        <td valign="top"><b>Description</b></td>
        <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
        <td valign="top">name</td>
        <td valign="top">Name of project library to include.</td>
        <td valign="top" align="center">No</td>
    </tr>
    <tr>
        <td valign="top">exported</td>
        <td valign="top">If true, this library will be exported to other modules
            that depend upon this module.
        </td>
        <td valign="top" align="center">No</td>
    </tr>
</table>


<h4>globalLibrary</h4>

<p>Depend on a global library. Global libraries are referred to by name.</p>
<table border="1" cellpadding="2" cellspacing="0">
    <tr>
        <td valign="top"><b>Attribute</b></td>
        <td valign="top"><b>Description</b></td>
        <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
        <td valign="top">name</td>
        <td valign="top">Name of global library to include.</td>
        <td valign="top" align="center">No</td>
    </tr>
    <tr>
        <td valign="top">exported</td>
        <td valign="top">If true, this library will be exported to other modules
            that depend upon this module.
        </td>
        <td valign="top" align="center">No</td>
    </tr>
</table>


<h4>module</h4>

<p>Depend on another module in the project.</p>
<table border="1" cellpadding="2" cellspacing="0">
    <tr>
        <td valign="top"><b>Attribute</b></td>
        <td valign="top"><b>Description</b></td>
        <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
        <td valign="top">name</td>
        <td valign="top">Name of module to include.</td>
        <td valign="top" align="center">No</td>
    </tr>
    <tr>
        <td valign="top">exported</td>
        <td valign="top">If true, this module will be exported to other modules
            that depend upon this module.
        </td>
        <td valign="top" align="center">No</td>
    </tr>
</table>


<h3>Examples</h3>

<p>A simple configuration that defines two source directories, and a tests
    directory, using nested tags.</p>

<blockquote><pre>
    &lt;ideamodule moduleFile="sample1.iml"
                    outputDir="${build.classes.dir}"
                    testsOutputDir="${build.test.classes.dir}"&gt;
      &lt;src path="${src.dir}"/&gt;
      &lt;src path="${src2.dir}"/&gt;
      &lt;tests refid="test.path"/&gt;
    &lt;/ideamodule&gt;
</pre>
</blockquote>


<p>A configuration that uses a classpath defined earlier in the build:</p>

<blockquote><pre>
    &lt;ideamodule moduleFile="sample2.iml"
                    srcdir="${src.dir}"
                    outputDir="${build.classes.dir}"
                    classpath="${build.classpath}"/&gt;
</pre>
</blockquote>


<p>A configuration that defines dependencies for the source and jdk:</p>

<blockquote><pre>
    &lt;ideamodule moduleFile="sample3.iml"
                    srcdir="${src.dir}"
                    outputDir="${build.classes.dir}"&gt;
      &lt;dependencies&gt;
        &lt;modulesource/&gt;
        &lt;jdk/&gt;
      &lt;/dependencies&gt;
    &lt;/ideamodule&gt;
</pre>
</blockquote>


<p>A configuration that uses a classpath defined earlier in the build,
    and uses the sourceproperty attribute to associate the source for a jar in
    the classpath:</p>

<blockquote><pre>
    &lt;property name="commons.lang.jar" location="lib/commons-lang-3.0.jar"/&gt;
    &lt;property name="source.commons.lang.jar"
              location="lib/commons-lang-3.0-src.jar"/&gt;
    &lt;property name="build.classpath" value="${commons.lang.jar}"/&gt;
    ...
    &lt;ideamodule moduleFile="sample4.iml"
                    sourceproperty="source"
                    srcdir="${src.dir}"
                    outputDir="${build.classes.dir}"
                    classpath="${build.classpath}"/&gt;
</pre>
</blockquote>


<hr>
<p align="center">Copyright &copy; 2006 Justin Tomich. All rights Reserved.</p>

</body>
</html>
